home *** CD-ROM | disk | FTP | other *** search
/ Collection of Tools & Utilities / Collection of Tools and Utilities.iso / c / clp_v11.zip / CLP.DOC next >
Text File  |  1989-10-14  |  21KB  |  577 lines
  1.  
  2.          CLP - A 'C' Command Line Processor, Version 1.1
  3.         -------------------------------------------------
  4.  
  5.  
  6. *****************************************************************
  7. *                                                               *
  8. *   This archived software set is shareware! It is NOT public-  *
  9. *   domain, and though it is free of charge it may only be      *
  10. *   distributed with the following conditions:                  *
  11. *                                                               *
  12. *      1.  The full archive CLP_V11.ARC is distributed without  *
  13. *          modification.                                        *
  14. *      2.  No commercial gain is directly sought from any of    *
  15. *          the files contained within the archive without the   *
  16. *          author's prior approval.                             *
  17. *      3.  Notification should be sent to the Author (name &    *
  18. *          address & e-Mail address below) of any use of CLP    *
  19. *          in programs outside the individual's personal use.   *
  20. *          This includes public-domain and shareware software   *
  21. *          as well as commercial software.                      *
  22. *                                                               *
  23. *  Users requiring versions of CLP for different memory models  *
  24. *  should send a postage paid reply envelope to the address     *
  25. *  below.  Registering may also be accomplished by sending a    *
  26. *  diskette (360K, 1.2M, 740K, 1.44M) to the address below. In  *
  27. *  reply, you will receive the latest version of CLP for all    *
  28. *  memory models, the complete CLPLIB utility and instructions  *
  29. *  for linking CLP definitions into code directly without the   *
  30. *  need for a library.                                          *
  31. *                                                               *
  32. *  Please ensure that the reply envelope has enough postage to  *
  33. *  cover costs.  Instead of postage, you may send a 1.44M       *
  34. *  diskette!  Gets around the international stamp system!       *
  35. *                                                               *
  36. *-  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  *
  37. *                                                               *
  38. *   Queries, comments, suggestions & registration to:           *
  39. *                                                               *
  40. *   Karl Keyte,                 e-Mail:  ESC1332@ESOC.BITNET    *
  41. *   E.S.O.C.,                   Phone :  +(49) 6151 886783      *
  42. *   Robert-Bosch Strasse 5,                                     *
  43. *   6100 Darmstadt                                              *
  44. *   West Germany                Date  :  September 1989         *              
  45. *                                                               *
  46. *****************************************************************
  47.  
  48.  
  49.  
  50.    
  51.  
  52. 1  Introduction
  53.    ------------
  54.  
  55.  
  56. CLP  is  a general purpose command  line  processor  for  the 'C'
  57. language.  Looking at the sources for various programs written in
  58. 'C'  it is clear that a lot of work has been repeated in handling
  59. command  line  options and parameters.  CLP  provides  a means by
  60. which the general format of the command line may be  defined in a
  61. Command  Line Definition file  (.CLD),  and processed by a single
  62. interface  call.  Following  that  call,  values and  settings of
  63. parameters and switches may  be queried by additional  calls. The
  64. idea and much  of  the flavour  of  CLP  comes  from  the VAX/VMS
  65. operating system, where command definitions may be build up  in a
  66. very similar fashion.
  67.  
  68.  
  69. CLP has been tested with Turbo-C (2.0) and Microsoft C (5.1). The
  70. '#include' file given  conforms  to  ANSI  standards,  and should
  71. therefore be  accepted  by  any ANSI compiler.  The object module
  72. uses a standard 'C' parameter stack.
  73.  
  74.  
  75. A  compiler  is  provided which takes the Command Line Definition
  76. file and generates a  Command  Line  Library  (.CLL)  file  which
  77. contains definitions for ALL utilities  using  the CLP interface.
  78. The .CLD  file  should  be  maintained  by  adding  and  deleting
  79. utilities from it as required. Running the compiler will generate
  80. the full Library file (.CLL) from the definitions.
  81.  
  82.  
  83. Four  functions  are   available  to  the   caller.  'clp_accept'
  84. initialises  the CLP processor for a  given  program  and command
  85. line.   'clp_get_spec'  returns  the  specification  code  for  a
  86. particular parameter or  switch  option.  'clp_get_value' returns
  87. the  value  associated  with  a  parameter  or  switch  option if
  88. present. These are described in detail in the following sections.
  89. When parameter and switch processing has been completed, the user
  90. may  recover  certain  portions  of  system memory by calling the
  91. procedure 'clp_release'.
  92.  
  93.  
  94.  
  95. 2  Interface Calls
  96.    ---------------
  97.  
  98.  
  99. 2.1  clp_accept
  100.      ----------
  101.  
  102.  
  103. Function:
  104.        Initialise CLP for specified program and command line.
  105.  
  106.  
  107. Syntax:
  108.        #include "clp.h"
  109.        void clp_accept ( char *function, int argc, char argv** );
  110.  
  111.  
  112. Prototype:
  113.        clp.h
  114.  
  115.  
  116. Remarks:
  117.        Sets  up  the data  structures  in  preparation  for other
  118.        interface calls. 'function' specifies the program name, as
  119.        given in the CLD file.  'argc'  and 'argv' are the command
  120.        line parameters of the main program,  and should be passed
  121.        to 'clp_accept' exactly as they were received.
  122.  
  123.        If  the  command   specified  does  not  conform   to  the
  124.        definition in the CLD, the program will exit with the exit
  125.        status of 1.
  126.  
  127.        'clp_accept'  attempts to  open  the CLL  library  file by
  128.        checking first the environment variable CLPLIB. If this is
  129.        defined,  the file given will be used.  If the environment
  130.        variable is undefined, 'clp_accept' attempts to locate the
  131.        file CLP.CLL in  the  current  searchpath.  If  it  is not
  132.        found, the program will exit with an exit code of 1.
  133.  
  134.  
  135. Return Value:
  136.        None.
  137.  
  138.  
  139.  
  140. 2.2  clp_get_spec
  141.      ------------
  142.  
  143.  
  144. Function:
  145.        Returns the  specification code  for a specified parameter
  146.        or switch option.
  147.  
  148.  
  149. Syntax:
  150.        #include "clp.h"
  151.        int clp_get_spec ( char *name );
  152.  
  153.  
  154. Remarks:
  155.        Finds the specification  associated  with  the  switch  or
  156.        parameter 'name'.  The  name  must  be  present in the CLD
  157.        file.
  158.  
  159.  
  160. Return Value:
  161.        The return is one of the following:
  162.  
  163.                 CLP_ERROR           Not   found,   i.e.  was  not
  164.                                     defined in the CLD file.
  165.                 CLP_NOTSPECIFIED    Not specified in  the command
  166.                                     line.
  167.                 CLP_DEFAULTED       Not specified in  the command
  168.                                     line but is on by default.
  169.                 CLP_SPECIFIED       Explicitly    specified    in
  170.                                     command line.
  171.                 CLP_VALUEDEFAULTED  Contains  a  value  which has
  172.                                     been defaulted.
  173.                 CLP_VALUESPECIFIED  Contains  a  value  which has
  174.                                     been explicitly specified.
  175.                 CLP_NEGATED         Explicitly negated.
  176.  
  177.  
  178.  
  179. 2.3  clp_get_value
  180.      -------------
  181.  
  182.  
  183. Function:
  184.        Returns  the value associated  with  a parameter  or value
  185.        switch option.
  186.  
  187.  
  188. Syntax:
  189.        #include "clp.h"
  190.        char *clp_get_value ( char *name );
  191.  
  192.  
  193. Remarks:
  194.        Finds the value asociated with the specified  parameter or
  195.        switch option, 'name'. The name must be present in the CLD
  196.        file.
  197.  
  198.  
  199. Return Value:
  200.        Returns  a pointer to  the  value  string.  The  string is
  201.        static,  and  must be copied  by the  user if it  is to be
  202.        further used.  NULL is returned if no value is defined, or
  203.        if  the 'name'  specifies an  invalid parameter  or switch
  204.        name.
  205.  
  206.  
  207.  
  208. 2.4  clp_release
  209.      -----------
  210.  
  211.  
  212. Function:
  213.        Releases all memory reserved by the CLP processor.
  214.  
  215.  
  216. Syntax:
  217.        #include "clp.h"
  218.        void clp_release ( void );
  219.  
  220.